\chapter[Events and Callbacks]{Events and Callbacks}

\section{Events and Callbacks}

\GRID is designed to smoothly integrate inside your own web page and to nicely interact
with your environment. \GRID fires a lot of events you can intercept to make \GRID behave
the way you like it.\\
Some of the \GRID behaviours can be set through some \GRID methods (for eg. \texttt{set\_cell\_click()})
while others are set by simply change an attribute value.\\
In this chapter, I'll tell you all the way you can control your \GRID once on a web page.

\section{Public Callbacks}
As the name suggests, \textit{public callbacks} are functions that will be called when an event occurs, 
and they are implemented as public \GRID attributes. At the moment, the following callbacks are defined:

\bl
\titem{\texttt{onchange}}{
	This function is called every time the user changes some contents inside the \GRID.\\
	So, in order to this callback to take effect, the \GRID has to be editable.\\
	The called function should have the following prototype: \\

\begin{FUNC}{onchange callback}
	\NAME{onchange\_callback ( grid, x, y, new\_val )}
	\SYNOPSIS{ (void) onchange\_callback ( grid, x, y, new\_val ) }
	\INPUT
	{
		\INPUTITEM{grid}{The grid object which has fired the event.}
		\INPUTITEM{x}{X coordinate of the cell having its values changing.}
		\INPUTITEM{y}{Y coordinate of the cell having its values changing.}
		\INPUTITEM{new\_val}{The new value contained inside the cell.}
	}
\end{FUNC}
\\
Here there is a code snipped to show you how to use the \texttt{onchange} attribute.
\\
\texttt{
	function val\_changed ( grid, x, y, new\_val ) \\
	\LBRACE\\
		alert ( "On grid: " + grid.id + " x: " + x + " y: " + y + " - value changed to: " + new\_val );\\
	\RBRACE\\
\\
	g.onchange = val\_changed;
	}
}
\titem{\texttt{onrender}}{This function is called every time the \GRID is rendered on the webpage. 
It can be used, for example, to update something else on your webpage.
The called function should have the following prototype: \\

\begin{FUNC}{onrender callback}
	\NAME{onrender\_callback ( grid )}
	\SYNOPSIS{ (void) onrender\_callback ( grid ) }
	\INPUT
	{
		\INPUTITEM{grid}{The grid object which has fired the event.}
	}
\end{FUNC}
}

\titem{\texttt{onrowselect}}{This function is called every time user selects or deselects a row.
The called function should have the following prototype: \\

\begin{FUNC}{onrowselect callback}
	\NAME{onrowselect\_callback ( grid, rownum, selected )}
	\SYNOPSIS{ (void) onrowselect\_callback ( grid, rownum, selected ) }
	\INPUT
	{
		\INPUTITEM{grid}{The grid object which has fired the event.}
		\INPUTITEM{rownum}{Number of the row the user has clicked on.}
		\INPUTITEM{selected}{Flag true/false telling you if the row is now selected or deselected.}
	}
\end{FUNC}
}
\el

\pagebreak
\section{Setting Events}
In this section, I'll list all methods you can use to set \GRID callbacks on special items.\\
\\
% {{{ set_cell_click ( cback ) - Sets cell click callback
\begin{FUNC}{set\_cell\_click}
	\NAME{set\_cell\_click ( func ) - Sets cell click callback}
	\SYNOPSIS{( void ) set\_cell\_click ( func )}
	\DESCRIPTION
	{
		When the user clicks on a cell, the \GRID can be instructed to set the cell as selected or 
		deselected (or simply do nothing). If you want to use this advanced feature, you have to
		provide a JavaScript function that should return \texttt{true} if the cell has to be selected
		and \texttt{false} if not.\\
		Function callback prototype is the following:\\
		\\
		\begin{FUNC}{cell\_clicked callback}
			\NAME{cell\_clicked\_callback ( grid, cell, x, y, val ) }
			\SYNOPSIS{ (void) cell\_clicked\_callback ( grid, cell, x, y, val )}
			\INPUT
			{
				\INPUTITEM{grid}{The grid object which has fired the event.}
				\INPUTITEM{cell}{The grid object which has fired the event.}
				\INPUTITEM{x}{X coordinate of the cell in the \GRID.}
				\INPUTITEM{y}{Y coordinate of the cell in the \GRID.}
				\INPUTITEM{val}{Current cell value.}
			}
			\end{FUNC}
	}

	\INPUT
	{
		\INPUTITEM{func}{Function callback}
	}
	\OUTPUT{ This method returns nothing. }
\end{FUNC}
% }}}
\\
% {{{ set_click_cb ( col, cback ) - Sets column click callback 
\begin{FUNC}{set\_click\_cb}
	\NAME{set\_click\_cb ( col, func ) - Sets column click callback}
	\SYNOPSIS{( void ) set\_click\_cb ( colnum, func )}
	\DESCRIPTION
	{
		When the \GRID is set to be \texttt{sortable} (using \texttt{set\_sortable}), all the headers 
		columns become user-clickable and fire the \texttt{sort()} event.\\
		You may wish to change this behaviour in two different ways:
		\be
		\item by blocking a particular column from firing the \texttt{sort()} event
		\item by providing a different, custom, callback to be fired in place of the \texttt{sort()} one.
		\ee

		To block a column from firing the \texttt{sort()} event, simply provide \texttt{-1} as function
		callback.\\
		To provide a different, custom callback, pass the name of the function as the \texttt{func} element.
		Function callback prototype is the following:\\
		\\
		\begin{FUNC}{header\_clicked callback}
			\NAME{header\_clicked\_callback ( grid, colnum ) }
			\SYNOPSIS{ (void) header\_clicked\_callback ( grid, colnum ) }
			\INPUT
			{
				\INPUTITEM{grid}{The grid object which has fired the event.}
				\INPUTITEM{colnum}{Column clicked by the user.}
			}
		\end{FUNC}
	}

	\INPUT
	{
		\INPUTITEM{colnum}{Header column number to set the function callback to.}
		\INPUTITEM{func}{Function callback. Pass \texttt{-1} to block the provided column to stop firing any event.}
	}
	\OUTPUT{ This method returns nothing. }
\end{FUNC}
% }}}

